Skip to content

Make an index of authors #89#141

Merged
RichardLitt merged 2 commits into
mainfrom
authors-as-pages-issue-89
Jun 3, 2026
Merged

Make an index of authors #89#141
RichardLitt merged 2 commits into
mainfrom
authors-as-pages-issue-89

Conversation

@RichardLitt
Copy link
Copy Markdown
Member

@RichardLitt RichardLitt commented May 23, 2026

Closes #89.

What this changes

Right now, contributors are listed as plain text bullets at the bottom of each pattern, and that's the only place their name appears on the website. If you've contributed to five patterns, your name lives in five different places — and there's no single page that shows everything you've worked on.

This PR adds a page for every author. Each author page shows their name, affiliation, ORCID, and the list of patterns they've contributed to. There's also a new Authors link in the top navigation that takes you to the full list of contributors.

What changes for someone writing or editing a pattern

Two small steps instead of one:

  1. Add yourself once to authors.yml at the root of the repo. This is where your name, ORCID, and affiliation live — you only put them in once, no matter how many patterns you contribute to. A short slug like jane-doe identifies you.
  2. List your slug in the pattern's frontmatter, under authors:. That's it.

You no longer type your name and ORCID at the bottom of each pattern — the site fills that section in for you. CONTRIBUTING.md has been updated with the new instructions and an example.

If you'd like to keep a note in the Contributors section (for example, the "A note on AI use" paragraph on the onboarding-graduate-leads pattern), you still can — anything written below the auto-generated author list is preserved.

What readers see that's new

  • A new Authors link in the top navigation.
  • A page for every contributor — for example /authors/ciara-flanagan/ — listing their affiliation, ORCID, and every pattern they've worked on.
  • On a pattern page, the Contributors section now shows each author as a clickable link to their author page (instead of plain text).

What to click on the preview site to see it working

Two patterns have been migrated as examples — the rest stay exactly as they are for now:

  • /embed-wellbeing-into-student-hackathons/ — scroll to the bottom; the six contributors are now clickable links to their author pages.
  • /onboarding-graduate-leads-for-open-source-internship-programs/ — same idea, plus the existing "A note on AI use" paragraph still appears underneath, untouched.
  • /authors/ — the new index of all authors.
  • /authors/ciara-flanagan/ — example of a single author page. Ciara appears in both example patterns, so her page lists both.
  • Any other pattern (for example /cohosting-student-events/) — unchanged; its hand-written contributor list still renders the way it always has.

What's coming next

This PR only migrates two patterns as proof of concept. The remaining ~46 patterns will be migrated to the new format in a follow-up PR — nothing breaks for them in the meantime, they keep working exactly as before until they're migrated.

A separate follow-up PR will also add the official ORCID iD logo next to ORCID links on author pages, for visual polish.

🤖 Generated with Claude Code

This was referenced May 23, 2026
Merged
Merged
Merged
@RichardLitt
Copy link
Copy Markdown
Member Author

RichardLitt commented May 27, 2026

Update on the design — after another look, I've reworked this so there's one Authors page instead of a separate page per author.

What's the same: authors.yml and the authors: frontmatter in each pattern work exactly the same. Contributing instructions are unchanged.

What's different on the site:

  • /authors/ is now a single page. It opens with a table of every contributor (name, affiliation, ORCID), and below the table there's a short section for each author listing the patterns they've worked on.
  • There are no longer /authors/ciara-flanagan/-style routes — each author has an anchor on the single page instead (e.g. /authors/#ciara-flanagan).
  • On a pattern's Contributors section, each name now links to that author's anchor on the Authors page.

The reasoning: most authors only have a pattern or two, so individual pages felt thin. A single page makes it easier to scan everyone at once, and you can still click a name on a pattern to jump straight to that person's entry.

The PR description above still describes the old approach — please ignore that part and treat this comment as the current behaviour. (Will tidy the description before merge.)

RichardLitt added a commit that referenced this pull request May 27, 2026
@RichardLitt
Migrate remaining patterns to frontmatter authors
4780eb6 
Convert all remaining patterns' Contributors sections to the
authors.yml + frontmatter model introduced in #141. Adds 28 new
authors to authors.yml (the 9 seeded in #141 stay unchanged) and
populates the `authors:` frontmatter on 41 patterns.

Migration was driven by a one-off Python script (not committed)
that:

- Parses each pattern's `## Contributors & Acknowledgement` /
  `Acknowledgements` section, skipping any "in alphabetical order"
  preamble.
- Extracts (name, affiliation, orcid) from each bullet using
  regex-based ORCID detection and a name/affiliation parser that
  handles both `Name, Affiliation, <orcid>` and `Name (Affiliation),
  <orcid>` shapes.
- Strips academic titles (Dr./Prof./etc.) before slug generation
  and before name-based deduplication, so "Dr. Angela Newell" maps
  to the existing `angela-newell` slug instead of creating a
  duplicate.
- Folds diacritics for slug generation via unicodedata.normalize
  (NFKD + combining-character strip), so "David Pérez-Suárez"
  becomes `david-perez-suarez` rather than `david-p-rez-su-rez`.
- Dedupes by ORCID first, then by case-insensitive name; backfills
  missing ORCID or affiliation on existing records when a later
  pattern provides one.
- Preserves any trailing prose under the Contributors heading
  (e.g. AI-use disclaimers, "Special thanks to X for ..." notes).

Skipped (no Contributors section, intentionally left untouched):
framework-managing-university-oss.md, lunch-and-learn.md,
open-research-community-accelerator.md, open-source-catalog.md,
open-source-software-prize.md, open-source-survey.md,
oss-tutorials-using-authoring-tools.md, summer-internship-program.md,
integrating-oss-into-institutional-software-pathways.md.

Verified:
- `mkdocs build --strict --site-dir /tmp/patterns_site` clean.
- All 37 author pages generate; each lists the patterns the author
  contributed to.
- Preserved prose still renders on
  individual-consultations-office-hours.md (Duane O'Brien thanks),
  source-industry-mentors-for-the-icorps-program.md (Jeffrey Young
  thanks), project-rolodex.md (Megan Forbes thanks), and the
  several patterns with "A note on AI use" paragraphs.
- `npm run lint` passes (one MD012 stray blank line in
  project-rolodex.md auto-fixed by `lint-fix`).
@RichardLitt
Add per-author pages via mkdocs hook (refs #89)
4916cc6 
Introduce a central authors.yml at the repo root and a small mkdocs hook
(.config/hooks/authors.py) that, on every build:

- Loads authors.yml (slug -> {name, orcid, affiliation}).
- Walks pattern frontmatter for `authors:` (a list of slugs) and builds a
  reverse slug -> [patterns] map; fails the build with a PluginError if a
  pattern references a slug missing from authors.yml.
- Emits one generated File per author at authors/<slug>.md plus an
  authors/index.md listing all authors alphabetically.
- In on_page_markdown, replaces the bullet list under
  `## Contributors & Acknowledgement` with chips linking to the author
  pages, preserving any prose that follows (e.g. AI-use disclaimers).
- Leaves patterns without an `authors:` frontmatter entry untouched so the
  remaining ~46 patterns continue to render their handwritten lists during
  gradual migration.

Config wiring:
- mkdocs.yml: register hooks/authors.py, add `Authors: authors/index.md`
  to nav, and exclude /authors.yml from the docs tree.

Template + contributor docs:
- PATTERN-TEMPLATE.md: add commented `authors:` block in frontmatter and
  rewrite the Contributors section to explain the new auto-generation.
- CONTRIBUTING.md: replace the "add your name and ORCID at the bottom"
  instruction with the two-step authors.yml + frontmatter flow.

Example migrations (exercise both code paths in the hook):
- embed-wellbeing-into-student-hackathons.md: 6 authors, no trailing prose.
- onboarding-graduate-leads-for-open-source-internship-programs.md:
  4 authors followed by an "A note on AI use" paragraph that the hook
  must preserve.

Verified with `mkdocs build --strict --site-dir /tmp/patterns_site`:
clean build, all 9 author pages generated, both migrated patterns render
chips correctly, AI-use paragraph preserved, non-migrated pattern
unchanged, and a negative test with an unknown slug aborts the build
with a clear error message.
@RichardLitt
Replace per-author pages with a single authors page (refs #89)
1472ef0 
The hook now generates only authors/index.md — a roster table plus one
anchored section per author with their patterns — instead of one page per
author. Pattern Contributors bullets link to authors/index.md#<slug>
anchors. Enables attr_list so { #slug } heading IDs are stable.
@RichardLitt RichardLitt force-pushed the authors-as-pages-issue-89 branch from 8e3f664 to 1472ef0 Compare June 3, 2026 01:08
@RichardLitt RichardLitt changed the title Give every author their own page (issue #89) Make an index of authors #89 Jun 3, 2026
@RichardLitt RichardLitt merged commit e6e7c4e into main Jun 3, 2026
1 of 2 checks passed
RichardLitt added a commit that referenced this pull request Jun 3, 2026
@RichardLitt
Migrate remaining patterns to frontmatter authors
ed9f013 
Convert all remaining patterns' Contributors sections to the
authors.yml + frontmatter model introduced in #141. Adds 28 new
authors to authors.yml (the 9 seeded in #141 stay unchanged) and
populates the `authors:` frontmatter on 41 patterns.

Migration was driven by a one-off Python script (not committed)
that:

- Parses each pattern's `## Contributors & Acknowledgement` /
  `Acknowledgements` section, skipping any "in alphabetical order"
  preamble.
- Extracts (name, affiliation, orcid) from each bullet using
  regex-based ORCID detection and a name/affiliation parser that
  handles both `Name, Affiliation, <orcid>` and `Name (Affiliation),
  <orcid>` shapes.
- Strips academic titles (Dr./Prof./etc.) before slug generation
  and before name-based deduplication, so "Dr. Angela Newell" maps
  to the existing `angela-newell` slug instead of creating a
  duplicate.
- Folds diacritics for slug generation via unicodedata.normalize
  (NFKD + combining-character strip), so "David Pérez-Suárez"
  becomes `david-perez-suarez` rather than `david-p-rez-su-rez`.
- Dedupes by ORCID first, then by case-insensitive name; backfills
  missing ORCID or affiliation on existing records when a later
  pattern provides one.
- Preserves any trailing prose under the Contributors heading
  (e.g. AI-use disclaimers, "Special thanks to X for ..." notes).

Skipped (no Contributors section, intentionally left untouched):
framework-managing-university-oss.md, lunch-and-learn.md,
open-research-community-accelerator.md, open-source-catalog.md,
open-source-software-prize.md, open-source-survey.md,
oss-tutorials-using-authoring-tools.md, summer-internship-program.md,
integrating-oss-into-institutional-software-pathways.md.

Verified:
- `mkdocs build --strict --site-dir /tmp/patterns_site` clean.
- All 37 author pages generate; each lists the patterns the author
  contributed to.
- Preserved prose still renders on
  individual-consultations-office-hours.md (Duane O'Brien thanks),
  source-industry-mentors-for-the-icorps-program.md (Jeffrey Young
  thanks), project-rolodex.md (Megan Forbes thanks), and the
  several patterns with "A note on AI use" paragraphs.
- `npm run lint` passes (one MD012 stray blank line in
  project-rolodex.md auto-fixed by `lint-fix`).
RichardLitt added a commit that referenced this pull request Jun 3, 2026
@RichardLitt
Add an RSS feed of new patterns with ORCID author links
658fd82 
The feed lists each pattern by first-publication date and credits every
author with a clickable link to their ORCID profile. Subscribers can
find it via the Material-emitted autodiscovery <link> tag, the new
"Stay in the loop" section on the home README, or the subscribe line
on every author page.

How it works:

- mkdocs-rss-plugin (pinned in .config/requirements.txt) generates the
  feed; filenames are left at the plugin defaults so Material's hard-
  coded autodiscovery URLs resolve correctly.
- .config/hooks/authors.py enriches each pattern's page metadata so the
  plugin sees real author names and an ORCID-linked attribution body.
  After build, the same hook post-processes the generated XML for spec
  compliance: <author> → <dc:creator>, item-level <description> wrapped
  in CDATA so the ORCID anchor tags render in feed readers, the self-
  referencing <source> element dropped, and unescaped categories
  (e.g. "Education & Skills") re-escaped to keep the feed well-formed.
- authors.yml entries are now validated at build time. Slugs, names,
  affiliations, and ORCIDs must match strict regexes; any HTML-tag
  character in a name or affiliation fails the build. This closes a
  stored-XSS hole that would otherwise let a malicious PR inject script
  via author metadata.

Follow-ups to file as separate GitHub issues:

1. Broader feed coverage — per-tag feeds, an Atom variant, and a JSON
   Feed mirror so modern readers (NetNewsWire, Feedbin) have a
   first-class option.

2. Scholarly identifiers — DOIs per pattern via Zenodo, ROR IDs for
   affiliations, and surfacing both in the feed metadata so scholarly
   graph crawlers (OpenAlex, CrossRef) can ingest the catalogue.

3. Tests + UX iteration — unit tests for the authors hook (the
   pre-merge review surfaced concrete failure cases worth pinning),
   an RSS icon for the subscribe affordance, consistent wording across
   the three subscribe surfaces, and revisiting the per-author
   placement which currently sits below the patterns list.

Stacked on top of #141 (author pages) and #142 (ORCID iD icon).
RichardLitt added a commit that referenced this pull request Jun 3, 2026
@RichardLitt
Migrate every remaining pattern to the new author system (#143)
da0f750 
* Normalize bullet markers to dashes (MD004)

Tighten .markdownlint.yaml to require `style: dash` for the
markdownlint MD004 (ul-style) rule, then run `npm run lint-fix`
to normalize all existing patterns to use `-` as the unordered
list marker (previously a mix of `-`, `*`, and `+`).

Pure auto-fix — no content changes, no whitespace changes beyond
the bullet character itself. Confirmed `npm run lint` passes
afterwards.

Prep for the upcoming bulk authors migration; consistent bullet
markers make the Contributors-section parser much simpler.

* Normalize edge cases in Contributors sections

Hand-fix four patterns whose Contributors sections didn't fit the
standard "bullet list of authors followed by optional prose" shape,
so the upcoming bulk migration can parse them consistently.

- event-tabling.md, ospo-student-ambassador-program.md: contributor
  entries were paragraph-form rather than a bulleted list. Convert
  each line to a `-` bullet. Also strip the `my-orcid?orcid=` query
  prefix from the Nouha Elyazidi ORCID URL so it matches the
  canonical `https://orcid.org/<id>` form.
- source-industry-mentors-for-the-icorps-program.md: the Zach Chandler
  line had a stray `](<https://orcid.org/...>` fragment left over
  from a half-applied markdown link. Remove the trailing junk so
  only the canonical ORCID URL remains.
- template-for-1-1-campus-consultations.md: a bullet read
  "Duane O'Brien consulted on the design of the CMU OSPO project
  consultation template", which is acknowledgement prose rather than
  a structured contributor entry. Move it out of the bullet list and
  into a "Thanks to Duane O'Brien…" sentence below the list.

No semantic changes — same people credited, same ORCIDs, same prose.

* Migrate remaining patterns to frontmatter authors

Convert all remaining patterns' Contributors sections to the
authors.yml + frontmatter model introduced in #141. Adds 28 new
authors to authors.yml (the 9 seeded in #141 stay unchanged) and
populates the `authors:` frontmatter on 41 patterns.

Migration was driven by a one-off Python script (not committed)
that:

- Parses each pattern's `## Contributors & Acknowledgement` /
  `Acknowledgements` section, skipping any "in alphabetical order"
  preamble.
- Extracts (name, affiliation, orcid) from each bullet using
  regex-based ORCID detection and a name/affiliation parser that
  handles both `Name, Affiliation, <orcid>` and `Name (Affiliation),
  <orcid>` shapes.
- Strips academic titles (Dr./Prof./etc.) before slug generation
  and before name-based deduplication, so "Dr. Angela Newell" maps
  to the existing `angela-newell` slug instead of creating a
  duplicate.
- Folds diacritics for slug generation via unicodedata.normalize
  (NFKD + combining-character strip), so "David Pérez-Suárez"
  becomes `david-perez-suarez` rather than `david-p-rez-su-rez`.
- Dedupes by ORCID first, then by case-insensitive name; backfills
  missing ORCID or affiliation on existing records when a later
  pattern provides one.
- Preserves any trailing prose under the Contributors heading
  (e.g. AI-use disclaimers, "Special thanks to X for ..." notes).

Skipped (no Contributors section, intentionally left untouched):
framework-managing-university-oss.md, lunch-and-learn.md,
open-research-community-accelerator.md, open-source-catalog.md,
open-source-software-prize.md, open-source-survey.md,
oss-tutorials-using-authoring-tools.md, summer-internship-program.md,
integrating-oss-into-institutional-software-pathways.md.

Verified:
- `mkdocs build --strict --site-dir /tmp/patterns_site` clean.
- All 37 author pages generate; each lists the patterns the author
  contributed to.
- Preserved prose still renders on
  individual-consultations-office-hours.md (Duane O'Brien thanks),
  source-industry-mentors-for-the-icorps-program.md (Jeffrey Young
  thanks), project-rolodex.md (Megan Forbes thanks), and the
  several patterns with "A note on AI use" paragraphs.
- `npm run lint` passes (one MD012 stray blank line in
  project-rolodex.md auto-fixed by `lint-fix`).
RichardLitt added a commit that referenced this pull request Jun 3, 2026
@RichardLitt
Add an RSS feed of new patterns with ORCID author links (#144)
d5d6fbb 
The feed lists each pattern by first-publication date and credits every
author with a clickable link to their ORCID profile. Subscribers can
find it via the Material-emitted autodiscovery <link> tag, the new
"Stay in the loop" section on the home README, or the subscribe line
on every author page.

How it works:

- mkdocs-rss-plugin (pinned in .config/requirements.txt) generates the
  feed; filenames are left at the plugin defaults so Material's hard-
  coded autodiscovery URLs resolve correctly.
- .config/hooks/authors.py enriches each pattern's page metadata so the
  plugin sees real author names and an ORCID-linked attribution body.
  After build, the same hook post-processes the generated XML for spec
  compliance: <author> → <dc:creator>, item-level <description> wrapped
  in CDATA so the ORCID anchor tags render in feed readers, the self-
  referencing <source> element dropped, and unescaped categories
  (e.g. "Education & Skills") re-escaped to keep the feed well-formed.
- authors.yml entries are now validated at build time. Slugs, names,
  affiliations, and ORCIDs must match strict regexes; any HTML-tag
  character in a name or affiliation fails the build. This closes a
  stored-XSS hole that would otherwise let a malicious PR inject script
  via author metadata.

Follow-ups to file as separate GitHub issues:

1. Broader feed coverage — per-tag feeds, an Atom variant, and a JSON
   Feed mirror so modern readers (NetNewsWire, Feedbin) have a
   first-class option.

2. Scholarly identifiers — DOIs per pattern via Zenodo, ROR IDs for
   affiliations, and surfacing both in the feed metadata so scholarly
   graph crawlers (OpenAlex, CrossRef) can ingest the catalogue.

3. Tests + UX iteration — unit tests for the authors hook (the
   pre-merge review surfaced concrete failure cases worth pinning),
   an RSS icon for the subscribe affordance, consistent wording across
   the three subscribe surfaces, and revisiting the per-author
   placement which currently sits below the patterns list.

Stacked on top of #141 (author pages) and #142 (ORCID iD icon).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Filter by authors

1 participant

@RichardLitt